DOC: update the pandas.DataFrame.pct_change docstring #20310

myles · 2018-03-12T18:04:05Z

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
################### Docstring (pandas.DataFrame.pct_change)  ###################
################################################################################

Percentage change between the current and previous element.

This is useful in comparing the percentage of change in a time series
of elements.

Parameters
----------
periods : int, default 1
    Periods to shift for forming percent change.
fill_method : str, default 'pad'
    How to handle NAs before computing percent changes.
limit : int, default None
    The number of consecutive NAs to fill before stopping.
freq : DateOffset, timedelta, or offset alias string, optional
    Increment to use from time series API (e.g. 'M' or BDay()).
**kwargs : mapping, optional
    Additional keyword arguments are passed into
    `DataFrame.shift` or `Series.shift`.

Returns
-------
chg : Series or DataFrame
    The same type as the calling object.

Examples
--------
See the percentage change in a Series.

>>> s = pd.Series([90, 91, 85])
>>> s
0    90
1    91
2    85
dtype: int64
>>> s.pct_change()
0         NaN
1    0.011111
2   -0.065934
dtype: float64

See the percentage change in a Series where filling NAs with last
valid observation forward to next valid.

>>> s = pd.Series([90, 91, None, 85])
>>> s
0    90.0
1    91.0
2     NaN
3    85.0
dtype: float64
>>> s.pct_change(fill_method='ffill')
0         NaN
1    0.011111
2    0.000000
3   -0.065934
dtype: float64

Percentage change in French franc, Deutsche Mark, and Italian lira from
1 January 1980 to 1 March 1980.

>>> df = pd.DataFrame({
...     'FR': [4.0405, 4.0963, 4.3149],
...     'GR': [1.7246, 1.7482, 1.8519],
...     'IT': [804.74, 810.01, 860.13]},
...     index=['1980-01-01', '1980-02-01', '1980-03-01'])
>>> df
                FR      GR      IT
1980-01-01  4.0405  1.7246  804.74
1980-02-01  4.0963  1.7482  810.01
1980-03-01  4.3149  1.8519  860.13
>>> df.pct_change()
                  FR        GR        IT
1980-01-01       NaN       NaN       NaN
1980-02-01  0.013810  0.013684  0.006549
1980-03-01  0.053365  0.059318  0.061876

Percentage of change in GOOG and APPL stock volume.

>>> df = pd.DataFrame({
...     '2016': [1769950, 30586265],
...     '2015': [1500923, 40912316],
...     '2014': [1371819, 41403351]},
...     index=['GOOG', 'APPL'])
>>> df
          2016      2015      2014
GOOG   1769950   1500923   1371819
APPL  30586265  40912316  41403351
>>> df.pct_change(axis='columns')
      2016      2015      2014
GOOG   NaN -0.151997 -0.086016
APPL   NaN  0.337604  0.012002

See Also
--------
DataFrame.diff : see the difference of two columns
Series.diff : see the difference of two columns

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwargs'} not documented
		Unknown parameters {'**kwargs'}

jorisvandenbossche

Nice PR! Added a few comments

jorisvandenbossche · 2018-03-12T18:06:29Z

pandas/core/generic.py

        freq : DateOffset, timedelta, or offset alias string, optional
-            Increment to use from time series API (e.g. 'M' or BDay())
+            Increment to use from time series API (e.g. 'M' or BDay()).
+        kwargs : mapping, optional


kwargs : mapping, optional -> **kwargs

jorisvandenbossche · 2018-03-12T18:07:00Z

pandas/core/generic.py

-            Increment to use from time series API (e.g. 'M' or BDay())
+            Increment to use from time series API (e.g. 'M' or BDay()).
+        kwargs : mapping, optional
+            A dictionary of keyword arguments passed into


It's not a dictionary, but just additional keywords, so you cna make this ""Additional keyword arguments are passed .."

But on second thought, are there actually additional keywords for shift?

That's what it's mapped to

pandas/pandas/core/generic.py

Lines 7561 to 7562 in 7169830

rs = (data.div(data.shift(periods=periods, freq=freq, axis=axis,

**kwargs)) - 1)

jorisvandenbossche · 2018-03-12T18:09:11Z

pandas/core/generic.py


        Returns
        -------
-        chg : %(klass)s
+        chg : Series or DataFrame, same type as the input


'input' -> 'calling object'

jorisvandenbossche · 2018-03-12T18:09:31Z

pandas/core/generic.py

+        See Also
+        --------
+        pandas.DataFrame.diff : see the difference of two columns
+        pandas.Series.diff : see the difference of two columns


Can you move this above the "Examples" section?

Can also remove the pandas. prefix I think.

TomAugspurger · 2018-03-12T18:27:46Z

pandas/core/generic.py

        freq : DateOffset, timedelta, or offset alias string, optional
-            Increment to use from time series API (e.g. 'M' or BDay())
+            Increment to use from time series API (e.g. 'M' or BDay()).
+        **kwargs : mapping, optional


Can remove the type here. Just **kwargs.

TomAugspurger · 2018-03-12T18:28:08Z

pandas/core/generic.py

+            Increment to use from time series API (e.g. 'M' or BDay()).
+        **kwargs : mapping, optional
+            Additional keyword arguments are passed into
+            ``DataFrame.shift``/``Series.shift``.


Single backticks. "or" instead of /

TomAugspurger · 2018-03-12T18:28:37Z

pandas/core/generic.py


        Returns
        -------
-        chg : %(klass)s
+        chg : Series or DataFrame, same type as the calling object


change : Series or DataFrame The same type as the calling object.

TomAugspurger · 2018-03-12T18:30:29Z

pandas/core/generic.py


        Notes
        -----
-
        By default, the percentage change is calculated along the stat


I don't think most users will understand stat access. Best to remove this and only focus on Series / DataFrame.

TomAugspurger · 2018-03-12T18:30:51Z

pandas/core/generic.py

        By default, the percentage change is calculated along the stat
        axis: 0, or ``Index``, for ``DataFrame`` and 1, or ``minor`` for
        ``Panel``. You can change this with the ``axis`` keyword argument.
+
+        Percentage change in French franc, Deutsche Mark, and Italian lira from


Move under the "Examples" header.

TomAugspurger · 2018-03-12T18:31:14Z

pandas/core/generic.py

+        1980-01-01       NaN       NaN       NaN
+        1980-02-01  0.013810  0.013684  0.006549
+        1980-03-01  0.053365  0.059318  0.061876
+


Show an example with axis='columns'. Can use the same DataFrame, even though it's a silly example for axis=1.

TomAugspurger · 2018-03-12T18:31:29Z

pandas/core/generic.py

+        See Also
+        --------
+        pandas.DataFrame.diff : see the difference of two columns
+        pandas.Series.diff : see the difference of two columns


Can also remove the pandas. prefix I think.

codecov · 2018-03-12T18:55:08Z

Codecov Report

Merging #20310 into master will increase coverage by 0.02%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master   #20310      +/-   ##
==========================================
+ Coverage    91.7%   91.72%   +0.02%     
==========================================
  Files         150      150              
  Lines       49165    49165              
==========================================
+ Hits        45087    45099      +12     
+ Misses       4078     4066      -12

Flag	Coverage Δ
#multiple	`90.11% <100%> (+0.02%)`	⬆️
#single	`41.86% <0%> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/generic.py	`95.85% <100%> (ø)`	⬆️
pandas/plotting/_converter.py	`66.81% <0%> (+1.73%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7169830...a0dcac2. Read the comment docs.

Note that it's immedate, but configurable. no type on kwargs. Example with periods. Moved See Also.

TomAugspurger · 2018-03-12T20:19:09Z

Made some touchups. Thanks @myles!

jorisvandenbossche · 2018-03-12T20:25:07Z

@TomAugspurger small comment on when merging: can you remove all the different commit messages (in case of those DOC PRs it's mostly useless to keep them). It's maybe not that important and only my nitpicky self, but it's only a "click in box, ctrl-A, del" combo away :-)

TomAugspurger · 2018-03-12T20:53:13Z

👍

myles added 6 commits March 10, 2018 13:20

💡 Fix some basic stuff from the validator script.

41cb90f

💡 Add a quick example of the pct_change function.

f818921

💡 Add some see also topics to pct_change.

972e3b1

💡 Stop showing the private method.

6a4c0e6

💡 Add an exmaple of Series and a Series with a fill_method.

dc2cb5a

🚨 Fix a mistake with the docstring.

ea99c67

jorisvandenbossche reviewed Mar 12, 2018

View reviewed changes

💡 Update based off feedback from @jorisvandenbossche.

a0d8ee7

TomAugspurger added the Docs label Mar 12, 2018

TomAugspurger added this to the 0.23.0 milestone Mar 12, 2018

TomAugspurger reviewed Mar 12, 2018

View reviewed changes

💡 Update based off feedback from @TomAugspurger.

4ecaf62

Previous to prior

a0dcac2

Note that it's immedate, but configurable. no type on kwargs. Example with periods. Moved See Also.

TomAugspurger merged commit c76120f into pandas-dev:master Mar 12, 2018

	rs = (data.div(data.shift(periods=periods, freq=freq, axis=axis,
	**kwargs)) - 1)

Uh oh!

DOC: update the pandas.DataFrame.pct_change docstring #20310

DOC: update the pandas.DataFrame.pct_change docstring #20310

Uh oh!

Conversation

myles commented Mar 12, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Mar 12, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

TomAugspurger commented Mar 12, 2018

Uh oh!

jorisvandenbossche commented Mar 12, 2018

Uh oh!

TomAugspurger commented Mar 12, 2018

Uh oh!

Uh oh!

myles commented Mar 12, 2018 •

edited

Loading

codecov bot commented Mar 12, 2018 •

edited

Loading